home *** CD-ROM | disk | FTP | other *** search
/ Programmer Power Tools / Programmer Power Tools.iso / progjrn / pj_7_2.arc / PWCOMM2.ARC / WPMAUX.DOC < prev   
Text File  |  1988-12-04  |  8KB  |  219 lines
  1.  
  2.  
  3.  
  4.               WINAUX/PMAUX
  5.  
  6.              William S. Hall
  7.              3665 Benton Street, #66
  8.               Santa Clara, CA 95051
  9.  
  10.               Introduction
  11.  
  12.  
  13.      Winaux is a Windows program capable of displaying text sent
  14. to it by another window.  PMaux is the corresponding version for
  15. presentation manager.  Acting as a simple scrolling window, each
  16. performs many of the operations of an auxiliary terminal.  They
  17. are particularly useful for analyzing the behavior of Windows or
  18. PM functions and for print-statement debugging.
  19.  
  20.      We begin by describing Winaux.  Please read this section even
  21. if you are planning to use PMaux.
  22.  
  23.  
  24.               Using Winaux
  25.  
  26.      Winaux is very easy to use.  When Winaux runs, it leaves a
  27. copy of its Window handle in win.ini.  Another program can then
  28. write to Winaux by sending it a message using the call
  29.  
  30.     SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);
  31.  
  32. where hWnd is the window handle (which can be retrieved from
  33. win.ini), str is a string of characters, and len is its length. 
  34. In practice, the operation is made simpler by writing a function
  35. which will carry out the operations of retrieving the handle,
  36. calculating the length, and sending the message.  This function
  37. can be placed into an include file and used as needed by the
  38. target program.
  39.  
  40.      When Winaux exits, it resets the value of the handle in
  41. win.ini to 0.  Hence programs which test for a valid window
  42. handle before attempting the SendMessage call will not risk the
  43. danger of accessing an invalid window.
  44.  
  45.      Only one instance of Winaux is allowed.
  46.  
  47.      The very first time Winaux runs, it will choose a default
  48. position and size on the screen and write these parameters to
  49. win.ini.  The user can modify these values to place Winaux as
  50. desired.  A typical entry in win.ini is as follows:
  51.  
  52.     [Winaux]
  53.     x=100
  54.     y=275
  55.     cx=540
  56.     cy=75
  57.     hWnd=4589
  58.  
  59. This window will be positioned at pixel location (100,275) on the
  60. display and will be 540 pixels wide and 75 high.  On an EGA, this
  61. will place the window in the lower right corner.
  62.  
  63.      If you are using Winaux to help you debug a Windows program,
  64. then you will find it useful to experiment with the position and
  65. size and then add Winaux to your load or run line in win.ini.  As
  66. you go repeatedly through the compile-program, run-Windows,
  67. test-program, exit-Windows cycle, you will appreciate WINAUX more
  68. if you do not have to bother with running and positioning its
  69. window repeatedly.
  70.  
  71.      Winaux creates a text buffer with as many lines as your
  72. maximized display can show when using the system font. 
  73. Similarly, the number of characters per line is computed based on
  74. the maximum width of the display and the size of the system font.
  75.  
  76.      Lines are displayed at the bottom of the window and scroll
  77. upward.  The bigger the window the more lines will be visible. 
  78. Currently, there are no scroll bars, so once a line number
  79. exceeds the maximum number of lines, it is lost.
  80.  
  81.      Winaux converts newlines to a carriage-return line-feed
  82. pair.  A menu option allows you to kill this option.  However,
  83. lines are wrapped if they exceed the maximum number of horizontal
  84. characters on a line.
  85.  
  86.      To illustrate the program's application, we have included a
  87. simple Windows template called Smltpl in which an sprintf
  88. statement has been added at the top of the message loop.  All
  89. message parameters, and a counter, are printed to a buffer which
  90. is sent by the function auxprt to the Winaux window.  Auxprt
  91. itself is defined in the include file auxprt.h.
  92.  
  93.     long FAR PASCAL MainWndProc( hWnd, message, wParam, lParam )
  94.     HWND hWnd;
  95.     unsigned message;
  96.     WORD wParam;
  97.     LONG lParam;
  98.     {
  99.         PAINTSTRUCT ps;
  100.  
  101.         /* print messages to Winaux */
  102.         sprintf(auxbuf,"hWnd = %4x message = %4x wParam = %4x lParam = %8lx\n",
  103.                  hWnd, message, wParam, lParam);
  104.         auxprt(auxbuf);
  105.  
  106.             ........
  107.  
  108.  
  109. Near the top of the program is an include statement
  110.  
  111.     #include "auxprt.h"
  112.  
  113. The file auxprt.h is as follows (as far as Windows is concerned);
  114.  
  115.     char auxbuf[80];
  116.     auxprt(char *str)
  117.     {
  118.         HWND hWnd;
  119.         int len = strlen(str);
  120.  
  121.     #if defined(WINAUX)
  122.         hWnd = (HWND)GetProfileInt((LPSTR)"Winaux", (LPSTR)"hWnd", 0);
  123.         if (IsWindow(hWnd))
  124.             SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);
  125.     #endif
  126.     
  127.     .... /* code for PM */
  128.     }
  129.  
  130.      Whenever a message is received, sprintf formats it and hands
  131. it to auxbuf.  The function auxbuf reads the Winaux handle,
  132. computes the length of the string, verifies that the handle
  133. received is valid, and sends it to Winaux.
  134.  
  135.      You can watch the messages being displayed by running
  136. Winaux, then Smltpl.  The action is especially swift as the mouse
  137. is moved over the Smltpl window.  You can also run more than one
  138. instance of the program and see the messages for each.
  139.  
  140.      Although reading the handle from win.ini may seem wasteful,
  141. it is a solid guarantee that the handle retrieved is either valid
  142. (Winaux is running) or NULL (Winaux has exited).  Also note the
  143. use of SendMessage rather than PostMessage.  Since Winaux will be
  144. retrieving a long pointer to data, SendMessage insures that the
  145. pointer is valid during the time that the data is being
  146. displayed.
  147.  
  148.  
  149.                Using PMaux
  150.  
  151.      When PMaux runs, it leaves a copy of its window handle in
  152. os2.ini.  However, it is more difficult in PM to get the buffer
  153. from the other program over to PMaux since the data segment of
  154. one program is not accessible to another in protected mode.  In
  155. this case it is necessary to create a global, sharable buffer in
  156. the program calling PMaux, fill it, and pass the handle and the
  157. buffer length over to PMaux.  The following excerpt from auxprt.h
  158. describes the method.
  159.  
  160.     char auxbuf[80];
  161.     auxprt(char *str)
  162.     {
  163.         HWND hWnd;
  164.         int len = strlen(str);
  165.  
  166.     ... /* code for Windows */
  167.  
  168.     #if defined(PMAUX)
  169.         char hbuf[40];
  170.         SEL sel;
  171.         PCH pchBuf;
  172.         int i;
  173.  
  174.   /* get the string representation of the handle for pmaux from OS2.INI */
  175.         WinQueryProfileString(hAB, "PMaux", "hWnd", "", hbuf, 40);
  176.   /* convert to a handle */
  177.         hWnd = (HWND)atol(hbuf);
  178.   /* create a shared buffer which can be read by another process */
  179.         if (DosAllocSeg(len, &sel, SEG_GETTABLE) == 0) {
  180.       /* make a long pointer to the buffer */
  181.         pchBuf = MAKEP(sel,0);
  182.       /* load it up */
  183.            for (i = 0; i < len; i++)
  184.             *(pchBuf+i) = *(str+i);
  185.       /* send it over */
  186.             if (WinIsWindow(hAB, hWnd))
  187.             WinSendMsg(hWnd, WM_USER, (MPARAM)len, (MPARAM)sel);
  188.       /* free the buffer */
  189.         DosFreeSeg(sel);
  190.         }
  191.         else  /* error, ring the bell */
  192.         WinAlarm(HWND_DESKTOP, WA_WARNING);    
  193. #endif
  194.  
  195.      To illustrate its usage, we have included a Presentation
  196. Manager template Spmtpl especially modified to transmit all
  197. messages received in the message loop to PMaux.  The technique is
  198. similar to that used in the corresponding Windows program.
  199.  
  200.      Most of the other features of Winaux are applicable to PMaux
  201. except that the initial placement and size of the window cannot
  202. be modified.  This was done partly for simplicity.  However, in
  203. PM, one can run PMaux, size and place it one time, and leave it
  204. for the duration of the OS2 session.
  205.  
  206.  
  207.                  Remarks
  208.  
  209.      If you are trying to use Winaux or PMaux with a dynamic link
  210. library, you can still use the techniques described above for
  211. passing the message.  However, methods other than sprintf must be
  212. used to format the string since none of the printf family can be
  213. used when the stack segment does not coincide with the data
  214. segment of your program.
  215.  
  216.      Finally, note that both Spmtpl and Smltpl are very useful
  217. templates which can help you in starting your own Windows or PM
  218. program.
  219.